\chapter{The \module{ParsedSoap} module --- basic message handling}

This class represents an input stream that has been parsed as a SOAP
message.

\begin{classdesc}{ParsedSoap}{input\optional{, **keywords}}
Creates a \class{ParsedSoap} object from the provided input source.
If \code{input} is not a string, then it must be an object with a
\method{read()} method that supports the standard Python ``file read''
semantics.

The following keyword arguments may be used:

\begin{tableiii}{l|c|p{30em}}{textrm}{Keyword}{Default}{Description}
\lineiii{\code{envelope}}{\code{True}}{expect a SOAP Envelope}
\lineiii{\code{keepdom}}{\code{False}}{Do not release the DOM when this
object is destroyed. To access the DOM object, use the
{\method{GetDomAndReader()}} method. The reader object is necessary to 
properly free the DOM structure using {\method{reader.releaseNode(dom)}}.
\versionadded{1.2}}
\lineiii{\code{readerclass}}{\code{None}}{Class used to create DOM-creating
XML readers; described below.
\versionadded{1.2}}
\lineiii{\code{resolver}}{\code{None}}{Value for the \code{resolver}
attribute; see below.}
\lineiii{\code{trailers}}{\code{False}}{Allow trailing data elements
to appear after the \code{Body}.}
\end{tableiii}

\end{classdesc}

The following attributes of a \class{ParsedSoap} are read-only:

\begin{memberdesc}{body}
The root of the SOAP \code{Body} element.
Using the \method{GetElementNSdict()} method on this attribute can be useful
to get a dictionary to be used with the \class{SoapWriter} class.
\end{memberdesc}

\begin{memberdesc}{body_root}
The element that contains the SOAP serialization root; that is,
the element in the SOAP \code{Body} that ``starts off'' the data.
\end{memberdesc}

\begin{memberdesc}{data_elements}
A (possibly empty) list of all child elements of the \code{Body} other
than the root.
\end{memberdesc}

\begin{memberdesc}{header}
The root of the SOAP \code{Header} element.
Using the \method{GetElementNSdict()} method on this attribute can be useful
to get a dictionary to be used with the \class{SoapWriter} class.
\end{memberdesc}

\begin{memberdesc}{header_elements}
A (possibly empty) list of all elements in the SOAP \code{Header}.
\end{memberdesc}

\begin{memberdesc}{trailer_elements}
Returns a (possibly empty) list of all elements following the \code{Body}.
If the \code{trailers} keyword was not used when the object was
constructed, this attribute will not be instantiated and retrieving
it will raise an exception.
\end{memberdesc}

The following attribute may be modified:

\begin{memberdesc}{resolver}
If not \code{None},
this attribute can be invoked to handle absolute \code{href}'s in the SOAP data.
It will be invoked as follows:

\begin{methoddesc}{resolver}{uri, tc, ps, **keywords}
The \code{uri} parameter is the URI to resolve.
The \code{tc} parameter is the typecode that needs to resolve \code{href}; this
may be needed to properly interpret the content of a MIME bodypart, for example.
The \code{ps} parameter is the \class{ParsedSoap} object that is invoking
the resolution (this allows a single resolver instance to handle multiple
SOAP parsers).

Failure to resolve the URI should result in an exception being raised.
If there is no content, return \code{None}; this is not the same as an
empty string.
If there is content, the data returned should be in a form understandable
by the typecode.
\end{methoddesc}
\end{memberdesc}

The following methods are available:

\begin{methoddesc}{Backtrace}{elt}
Returns a human-readable ``trace'' from the document root to the
specified element.
\end{methoddesc}

\begin{methoddesc}{FindLocalHREF}{href, elt}
Returns the element that has an \code{id} attribute whose value is specified
by the \code{href} fragment identifier.
The \code{href} \emph{must} be a fragment reference --- that is, it must
start with a pound sign.
This method raises an \exception{EvaluateException} exception if the
element isn't found.
It is mainly for use by the parsing methods in the \module{TypeCode} module.
\end{methoddesc}

\begin{methoddesc}{GetElementNSdict}{elt}
Return a dictionary for all the namespace entries active at the
current element. Each dictionary key will be the prefix and the value will
be the namespace URI.
\end{methoddesc}

\begin{methoddesc}{GetMyHeaderElements}{\optional{actorlist=None}}
Returns a list of all elements in the \code{Header} that are intended for
\emph{this} SOAP processor.
This includes all elements that either have no SOAP \code{actor}
attribute, or whose value is either the special ``next actor'' value or
in the \code{actorlist} list of URI's.
\end{methoddesc}

\begin{methoddesc}{GetDomAndReader}{}
Returns a tuple containing the dom and reader objects, \code{(dom, reader)}.
Unless keepdom is true, the dom and reader objects will go out of scope
when the ParsedSoap instance is deleted. If keepdom is true, the reader
object is needed to properly clean up the dom tree with 
\method{reader.releaseNode(dom)}.
\end{methoddesc}

\begin{methoddesc}{IsAFault}{}
Returns true if the message is a SOAP fault.
\end{methoddesc}

\begin{methoddesc}{Parse}{how}
Parses the SOAP \code{Body} according to the \code{how} parameter,
and returns a Python object.
If \code{how} is not a \class{TC.TypeCode} object, then it should be a
Python class object that has a \code{typecode} attribute.
\end{methoddesc}

\begin{methoddesc}{ResolveHREF}{uri, tc\optional{, **keywords}}
This method is invoked to resolve an absolute URI.
If the typecode \code{tc} has a \code{resolver} attribute, it will use it
to resolve the URI specified in the \code{uri} parameter,
otherwise it will use its own \code{resolver}, or raise an
\exception{EvaluateException} exception.

Any \code{keyword} parameters will be passed to the chosen resolver.
If no content is available, it will return \code{None}.
If unable to resolve the URI it will raise an
\exception{EvaluateException} exception.
Otherwise, the resolver should return data in a form acceptable to the
specified typecode, \code{tc}.
(This will almost always be a file-like object holding opaque data;
for XML, it may be a DOM tree.)
\end{methoddesc}

\begin{methoddesc}{WhatActorsArePresent}{}
Returns a list of the values of all the SOAP \code{actor} attributes
found in child elements of the SOAP \code{Header}.
\end{methoddesc}

\begin{methoddesc}{WhatMustIUnderstand}{}
Returns a list of \samp{(uri, localname)} tuples for all elements in the
SOAP \code{Header} that have the SOAP \code{mustUnderstand} attribute set
to a non-zero value.
\end{methoddesc}

\ZSI{} supports multiple DOM implementations.
The \code{readerclass} parameter specifies which one to use.
The default is to use the DOM provided with the PyXML package developed
by the Python XML SIG, provided through the \class{PyExpat.Reader} class
in the \module{xml.dom.ext.reader} module.

The specified reader class must support the following methods:

\begin{methoddesc}{fromString}{string}
Return a DOM object from a string.
\end{methoddesc}

\begin{methoddesc}{fromStream}{stream}
Return a DOM object from a file-like stream.
\end{methoddesc}

\begin{methoddesc}{releaseNode}{dom}
Free the specified DOM object.
\end{methoddesc}

The DOM object must support the standard Python mapping of the DOM Level 2
specification.
While only a small subset of specification is used, the particular
methods and attributes used by \ZSI{} are available only
by inspecting the source.

To use the \code{cDomlette} DOM provided by the 4Suite package, use the
\class{NonvalidatingReader} class in the \module{Ft.Xml.Domlette} module.
Due to name changes in the 1.0 version of 4Suite, a simple adapter class
is required to use this DOM implementation. 

\begin{verbatim}
from 4Suite.Xml.Domlette import NonvalidatingReaderBase

class 4SuiteAdapterReader(NonvalidatingReaderBase):

    def fromString(self, str):
        return self.parseString(str)

    def fromStream(self, stream):
        return self.parseStream(stream)

    def releaseNode(self, node):
        pass
\end{verbatim}
